Editorial review: Document canvas context lang attribute

[chrisdavidmills]

Description

Chrome 136 supports the lang attribute for on- and off-screen canvas 2D drawing contexts: see https://chromestatus.com/feature/5066778773028864.

This PR adds documentation for the new attribute.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs

• /en-US/docs/Web/API/CanvasRenderingContext2D/lang
• /en-US/docs/Web/API/CanvasRenderingContext2D
• /en-US/docs/Web/API/OffscreenCanvasRenderingContext2D

External URLs (2)

URL: /en-US/docs/Web/API/CanvasRenderingContext2D/lang
Title: CanvasRenderingContext2D: lang property

• https://blogs.igalia.com/schenney/canvas-localization-support/ (1 time) (Note! This may be a new URL 👀)
• https://datatracker.ietf.org/doc/html/rfc5646 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-05-30 07:12:17)

[schenney-chromium]

Thanks so much for adding this.

The behavior of lang = inherit for the offscreen case is not super intuitive due to technical limitations with offscreen canvas. Any alternative would be even less intuitive because the behavior would depend on how the offscreen was created and whether it was used in a worker.

[schenney-chromium]

The inherit value behaves differently for Offscreen in that it is not dynamic. The inherited value is set when the offscreen is created, and then remains fixed for the lifetime of the offscreen. The spec text is An OffscreenCanvas object has an internal inherited language and inherited direction set when the OffscreenCanvas s created.. I think it's important to call this out in a paragraph following this one.

On the demo the best approach would be to set the lang attribute explicitly to the selected language. If fact, I think that's the only way to have the language change on the offscreen after creation.

[chrisdavidmills]

Fantastic, thank you for helping me understand this, @schenney-chromium!

So, I've added an explanation to the "Value" section, and also updated the off-screen demo to suit so that it works as expected (I've also added text to explain the difference between the demos).

Can you have another look and let me know what you think?

[schenney-chromium]

LGTM. Thanks again. Not sure if an MDN reviewer needs to also review, but I would recommend it as I am inexperienced with MDN style and conventions (at least from an authoring perspective).

[chrisdavidmills]

LGTM. Thanks again.

Great stuff, thanks for the tech review!

Not sure if an MDN reviewer needs to also review, but I would recommend it as I am inexperienced with MDN style and conventions (at least from an authoring perspective).

I always do a separate editorial review phase after the tech review, as a standard part of the procedure, so we're all good.

[wbamberg]

I do have some more detailed comments on this PR, that I'll get to, but my initial comment is that this seems to be burying the lede. As I understand things, the key message, and the reason this property exists, is like this:

• you sometimes need to set a language for a canvas, so it knows how to render (for example) language-dependent font features
• an on-screen canvas is always associated with a particular <canvas> element, so whenever you render content using it, it can derive the language from the value of the <canvas> element's lang attribute (which might be set on the <canvas> element itself or inherited from an ancestor).
• however, an off-screen canvas renders the content before it's associated with a <canvas> element, so it can't use the lang attribute of the <canvas> element for language-dependent rendering.

The lang property addresses this issue, allowing you to set a language directly on a canvas rendering context, whether you are using an offscreen canvas or not.

Is this correct? If so, I think we should say this, which we don't currently. There is some stuff like this, after "Due to technical limitations...", but these are presented as limitations of the inherit value, not of the Canvas API as a whole.

But I'm wondering my understanding is correct, because if it is, some other things are wrong. For example:

For off-screen canvases, the lang value is inherited when the associated OffscreenCanvasRenderingContext2D object is first created, and then fixed for the lifetime of the OffscreenCanvas.

...this presents the issue as just one of dynamic updates, but if I'm right, the lang value is not inherited from the lang attribute of the <canvas> at all for offscreen canvases. It seems to be inherited from the lang attribute of the document (i.e. the <html> element) - which makes sense, because the offscreen rendering context has no idea which <canvas> it will end up in.

[schenney-chromium]

I do have some more detailed comments on this PR, that I'll get to, but my initial comment is that this seems to be burying the lede. As I understand things, the key message, and the reason this property exists, is like this:

• you sometimes need to set a language for a canvas, so it knows how to render (for example) language-dependent font features
• an on-screen canvas is always associated with a particular <canvas> element, so whenever you render content using it, it can derive the language from the value of the <canvas> element's lang attribute (which might be set on the <canvas> element itself or inherited from an ancestor).
• however, an off-screen canvas renders the content before it's associated with a <canvas> element, so it can't use the lang attribute of the <canvas> element for language-dependent rendering.

The behavior is messy for offscreen. If the offscreen was transferred from a canvas element the inherit comes from that canvas, otherwise it comes from the best document we can find, typically the script realm.

The lang property addresses this issue, allowing you to set a language directly on a canvas rendering context, whether you are using an offscreen canvas or not.

Right, that's the biggest improvement.

Is this correct? If so, I think we should say this, which we don't currently. There is some stuff like this, after "Due to technical limitations...", but these are presented as limitations of the inherit value, not of the Canvas API as a whole.

But I'm wondering my understanding is correct, because if it is, some other things are wrong. For example:

For off-screen canvases, the lang value is inherited when the associated OffscreenCanvasRenderingContext2D object is first created, and then fixed for the lifetime of the OffscreenCanvas.

...this presents the issue as just one of dynamic updates, but if I'm right, the lang value is not inherited from the lang attribute of the <canvas> at all for offscreen canvases. It seems to be inherited from the lang attribute of the document (i.e. the <html> element) - which makes sense, because the offscreen rendering context has no idea which <canvas> it will end up in.

Mostly yes, except for the transferred context case. I went through all the complexity of describing this when writing the spec. I agree that giving the general outline then having a section specifically discussing the inherit value would be clearer. It is important there to say that inherit is the default, and the value comes from the most specific place that can be found: an associated canvas element if there is one, otherwise the document.

[chrisdavidmills]

I do have some more detailed comments on this PR, that I'll get to, but my initial comment is that this seems to be burying the lede.

I hear you, @wbamberg. I've just pushed a commit that adds the desired explanation to a new description section, along with the inherit behavior and limitations stuff.

This will probably require a bit more wrangling, as it is somewhat fiddly to make sense of, but I think we're getting close.